Windows Glulxe 0.5.1
(Windows Glk 1.44)

Windows Glulxe is an interpreter for Glulx games. Windows Glulxe consists of a core interpreter called Glulxe, and an input/output library, called Windows Glk. Together these two components form the Windows Glulxe package, which has been created by David Kinder.
Web: http://www.davidkinder.co.uk/
Email: davidk@davidkinder.co.uk

The latest release of Windows Glulxe is available from the Glulxe page at the IF Archive, which also contains many games that can be played with Windows Glulxe. For help on how to get started with Windows Glulxe, click here.

Windows Glulxe supports all the features of the Glk and Blorb specifications, including graphics (with alpha blending and gamma correction) and sound (as either samples or music). Windows Glulxe is based on Windows Glk by David Kinder, and Glulxe by Andrew Plotkin. Windows Glk and Glulxe are released under this license.


Getting Started

In order to use Windows Glulxe, you will need a Glulx game file to play on it. This format was invented by Andrew Plotkin to address the limitations of the widely used Z-code format (also referred to as the Z-Machine), which was originally invented by Infocom, Inc. for the games they released during the 1980s.

Members of the current interactive fiction community have written many games using Graham Nelson's compiler Inform. Inform can produce as output either Z-code or Glulx game files. Glulx games can be downloaded from the IF Archive at
http://www.ifarchive.org/indexes/if-archiveXgamesXglulx.html

When Windows Glulxe is first started, a file dialog opens, prompting you for a game file to load. This file can be either a Glulx file or a Blorb file. A Glulx file has a name ending with .ulx. A Blorb file contains multimedia resources for games, and can also contain the Glulx game as well. Blorb files have a name ending with .blb, .blorb, .glb or .gblorb.

Once a game file is selected, Windows Glulxe will open its main window and start running the game. If the game is packaged with an iFiction record, then the cover art and description is shown first.

Further information:

  • Menus and the toolbar
  • Editing keys
  • Changing options


Menus and the Toolbar

Windows Glulxe provides the following menu items, the most commonly used of which also appear on the toolbar:

Scrollback Ctrl+L
Opens the scrollback dialog, which shows all the text printed since the current game was started.

Fonts/Proportional Font...
Opens the font dialog for selecting the proportional font used for text in the game.

Fonts/Fixed Width Font...
Opens the font dialog for selecting the fixed-width font used for text in the game that needs a particular layout, such as the status bar, or any maps or symbols the game might display.

View/Options...
Opens the options dialog.

Help
Opens this help window.

About This Game
Opens a dialog showing the cover art and description of the game, if available.

About Glulxe
Opens the About dialog, which shows the version number and credits for this version of Windows Glulxe.

Exit Alt+F4
Exits the interpreter.


Editing Keys

When Windows Glulxe is waiting for input from the user, the following keys have special meanings:
Delete | Delete the character under the cursor.
Backspace | Delete the character to the left of the cursor.
Home | Move the cursor to the start of the input line.
End | Move the cursor to the end of the input line.
Cursor Left | Move the cursor to the left.
Cursor Right | Move the cursor to the right.
Cursor Up | Show the previous input in the input history.
Cursor Down | Show the next input in the input history.
Ctrl+Cursor Left | Move the cursor to the start of the current word, or the previous word if already at the start of a word.
Ctrl+Cursor Right | Move the cursor to the end of the current word, or the next word if already at the end of a word.
Tab | Move the input focus to the next window which is waiting for input.
Shift+Tab | Move the input focus to the previous window which is waiting for input.
Ctrl+Pause | Halts any speech currently being spoken.
Ctrl+V | Paste the contents of the clipboard into the input line.
Alt+Enter | Toggle full screen mode.

The hotkeys assigned to menu items are given here.


Changing Options

From the Options dialog, you can change the various display options of Windows Glulxe.

General Options

Borders between windows
If selected, windows that the game opens in the main interpreter window are surrounded by a standard window border.

Enable menus, toolbars and the status bar
If selected, the interpreter window has a menu bar, a toolbar and a status bar. If not selected, these items are not present. In either case, the options dialog is still always accessible from the system menu (that is, the menu obtained by clicking on the icon in the left corner of the interpreter's title bar).

Style hints override user settings
If selected, style hints set by the game override any style options selected by the user. The style options are described below.

Use a custom hyperlink colour
If selected, hyperlinks are displayed using the colour set by the colour chooser button to the right of this option.

Underline hyperlinks
If selected, hyperlinks are displayed underlined, as in most web browsers.

If the game has an iFiction record ...
When Windows Glulxe loads a game that contains an iFiction record, it may show the About This Game dialog. This option determines whether the dialog is never shown, only shown the first time, or shown every time.

Style Options

Note that changing the values discussed below will only affect new windows opened by the game, not any existing ones. Furthermore, if the game overrides any of these settings with style hints, then that particular style will not be editable.

Window
Determines the type of window for which the style is being edited. Text buffer windows are the normal windows in which output appears in the proportional font and the user enters input. Text grid windows always show text in a fixed width font and are used for tasks such as a status bar. Only some of the style options are relevant for text grid windows; the remainder are greyed out.

Style
Determines the particular style being edited.

Indentation
How much a paragraph in this style is indented, in arbitrary units.

Paragraph Indentation
How much the first line of a paragraph in this style is indented, in arbitrary units.

Justification
Whether paragraphs are drawn flush with the left margin, the right margin, both margins, or centered.

Text Size
The size of the text, measured in arbitrary units, relative to the default size determined by the user using the font dialogs from the menu or toolbar.

Text Weight
Whether the text is drawn normally, emphasized, or lightly.

Italic
If selected, text is drawn italicised.

Proportional
If selected, text is drawn using the proportional font. If not selected, the fixed-width font is used instead.

Reverse
If selected, text is drawn reversed, i.e. the background colour is used to draw the text, with the background set to the text colour.

Text Colour
The colour in which the text is drawn in.

Background
The colour in which the background behind the text is drawn.

Speech Options

Windows Glulxe can use Microsoft's Speech Engine 5 to speak text, which is present by default in Windows XP and later. If it is present, there is a Speech tab in in the options dialog, containing controls that allow speaking of the game's text to be turned on, and the voice and speed at which it is spoken in to be set.


Glulx

The Glulx specification was written by Andrew Plotkin as an attempt to define a format for interactive fiction games that the Inform compiler could compile to, without the limitations of its original output format, Infocom's Z-Machine.

Windows Glulxe is based on Andrew's Glulxe 0.5.1, which is a complete implementation of version 3.1.2 of the Glulx specification.

More information on Glulx is available from the Glulx web page: http://www.eblong.com/zarf/glulx/


Glk

The Glk specification was written by Andrew Plotkin as an attempt to define a standard input and output interface for general use in IF related projects. Windows Glulxe uses my (David Kinder) implementation of Glk, called Windows Glk. Windows Glk is a complete implementation of all the features described in version 0.7.4 of the Glk specification.

The complete Windows Glk package, including developer information, can be downloaded from the IF Archive's Glk implementations page.

More information on Glk is available from the Glk web page: http://www.eblong.com/zarf/glk/


Blorb

The Blorb specification was written by Andrew Plotkin as a way of providing graphics and sound resources for Z-code and Glulx games.

A Blorb file contains all the graphics and sound files needed for a game. It can also contain the Glulx code for the game as well, but does not need to: The game could also be distributed as separate Glulx and Blorb files. If you try to load a Blorb file into Windows Glulxe that does not contain a Glulx game, it will ask you to load the appropriate Glulx file into the interpreter instead.

Blorb files can contain JPEG and PNG graphics files, AIFF sound samples, and MOD and Ogg Vorbis music files. Windows Glulxe supports all of these formats, including transparency, opacity and gamma correction for PNG graphics.

From version 2.0, the Blorb specification also includes iFiction metadata and cover art chunks; Inform 7 can produce Blorb files containing these. If present, Windows Glulxe uses them to determine the title of the game and to populate the About This Game dialog.

More information on Blorb is available from the Blorb web page: http://www.eblong.com/zarf/blorb/


Graphics and Sound

Windows Glulxe can load graphics and sound resources either from within Blorb files or as separate files.

If a Blorb file is loaded into the interpreter, or a Blorb file exists with the same name as the Glulx game file, then graphics and sound resources will be looked for first in that Blorb file.

If Windows Glulxe cannot find a requested resource in the Blorb file (or there is no Blorb file), it will look for a suitably named file in the same directory as the game file. The resource formats currently supported are shown below, along with the filename for which the interpreter will look if the resource is not in the Blorb file (as an example, the filename is for resource number 1):

Format | Type | Example Filename
PNG | image | pic1.png
JPEG | image | pic1.jpg
AIFF | sound | snd1.aif or snd1.aiff
MOD | music | mus1.mod
OGGV | music | mus1.ogg


Configuration Files

Windows Glulxe can load a configuration file with the game that sets various attributes of the interpreter window. The configuration file should have the same name as the game except for an extension of .cfg.

The configuration file is a text file where each line contains a key name, followed by an equals sign, then a value, e.g. WindowBorders=no. Possible keys are:

WindowBorders=[yes/no] | Turns on or off borders between windows.
WindowFrame=[yes/no] | Turns on or off the interpreter window's frame, that is, the title bar and the border around the whole window.
WindowMask=[number] | Uses the given Blorb resource number to set the mask for the window from the graphic. If a particular pixel in the graphic is white then the window is transparent at that point, else it is opaque. This key only takes effect if "WindowFrame=no".
WindowWidth=[width] | Sets the width of the interpreter's window so that a single, full-size Glk window will have a width of the given value.
WindowHeight=[height] | Sets the height of the interpreter's window so that a single, full-size Glk window will have a height of the given value.
FullScreen=[yes/no] | If set to "yes", the interpreter's window opens filling the entire screen.
FontName=[font] | Sets the font used for proportional text to the given font name, e.g. Times New Roman.
FontSize=[size] | Sets the size of the font used for proportional text to the given value, measured in points.
FixedFontName=[font] | Sets the font used for fixed width text to the given font name.
FixedFontSize=[size] | Sets the size of the font used for fixed width text to the given value.


Automatic Running

When it comes time to distribute your game, you can package up the interpreter with your game into an archive or installer. But if you want the user to be able to start your game just by clicking on an icon, you can rename Glulxe.exe to the same as the name as your game's Glulx file (apart from the .exe file extension). When the interpreter starts up it first looks for a Blorb file with the same name as the executable, and if one is found, loads and runs it straight away. So, if your game file is Foo.blb and the renamed interpreter executable is Foo.exe, all the user needs to do to run your game is double click on Foo.exe.


The IF Archive

The IF Archive is the central site on the Internet for text adventures and related interpreters, compilers and other tools. The Archive has an unrivalled collection of material relating to text adventures, including something in the region of two thousand games.

Formerly at the FTP site ftp.gmd.de, it is now at the web site http://www.ifarchive.org/. The Archive is also still accessible through FTP, at ftp://ftp.ifarchive.org/if-archive/. You might also like to consider using one of the Archive's mirror sites, which are listed on the Archive's home page: depending on where you are, you might well find a mirror that responds faster than the main Archive site.

The Archive's main collection of Glulx games is in the games/glulx directory. Another source of Glulx games is the annual IF Competition. Two other sites well worth a look are Baf's Guide to the Archive and Mike Robert's Interactive Fiction Database, both of which provide information and reviews of games in the IF Archive.


Revision History

Glulxe 0.5.1 (Windows Glk 1.44)
  • Updated to Glulxe 0.5.1, which fixes a bug in reading from Glk streams.
Glulxe 0.5.0 (Windows Glk 1.44)
  • Updated to Glulxe 0.5.0, which fixes various bugs, and introduces new checks on the areas of memory that the game reads and writes to. This causes problems with some games written with the Superglus system: if this is a problem for you, a separate executable without these checks is provided as "Glulxe (no memory checks).exe".
Glulxe 0.4.7 (Windows Glk 1.44)
  • Updated to support Glk 0.7.4, which introduces resource streams (i.e. access to read-only data held in the Blorb game file).
Glulxe 0.4.7 (Windows Glk 1.43)
  • Updated to Glulxe 0.4.7, which fixes various bugs.
  • Updated to support Glk 0.7.3, which includes more control when playing sounds. This revision of the Glk specification also now specifies the meaning of the volume argument to sound related Glk calls: as a result the handling of the volume has been changed to match the specification.
  • [More] prompts now function even if the game has exited, allowing any long amount of final text to be read.
  • Fixed a bug with file streams when reading and writing to the same file.
Glulxe 0.4.6 (Windows Glk 1.42)
  • The accuracy of the time returned by glk_current_time() has been improved. Providing that the computer supports a sufficiently high resolution timer, the returned time is now correct to the nearest microsecond.
Glulxe 0.4.6 (Windows Glk 1.41)
  • Updated to support Glk 0.7.2, which includes functions for accessing the system's date and time.
  • Updated to support Glk 0.7.1, which includes functions for Unicode string decomposition and normalization, and control over line input echoing and terminator characters.
  • Unicode characters now appear correctly in the scrollback dialog, provided that the dialog font supports them.
Glulxe 0.4.6 (Windows Glk 1.40)
  • Corrected problems with formatting and line input when margin images are present.
  • Corrected a mistake in the handling of alpha-blended images.
Glulxe 0.4.6 (Windows Glk 1.39)
  • Updated to Glulxe 0.4.6, which implements the Glulx 3.1.2 specification. This adds support for floating point calculations (that is, non-integer numbers).
  • The window can be made to fill the entire screen; press Alt+Enter to toggle this full screen mode on and off.
  • A new configuration file option, "FullScreen", also makes the window fill the entire screen.
  • During line input, Ctrl+Left moves the cursor to the start of the current word, and Ctrl+Right moves to the end.
  • The logic when scaling alpha-blended images has been improved, so there should no longer be artifacts round the edges of such images.
  • Data being written to files is now flushed whenever input is requested from the user. This allows, for example, transcript files to update as a game is being played, and not only when the interpreter closes the file.
  • Corrected a problem which could result in the options dialog using the wrong font.
Glulxe 0.4.5 (Windows Glk 1.38)
  • Fixed a file creation bug in glk_stream_open_file().
Glulxe 0.4.5 (Windows Glk 1.37)
  • Updated to Glulxe 0.4.5, which fixes various obscure bugs that have been revealed by unit-testing.
Glulxe 0.4.4 (Windows Glk 1.37)
  • Clicking on a Glk window now only shifts the keyboard input focus to that window if the window is capable of text input: this means that after clicking on a graphics window, text can still be input in a text buffer window without having to click back to the text buffer window.
  • The implementation of the algorithm for scaling images has been sped up again.
Glulxe 0.4.4 (Windows Glk 1.36)
  • Updated to Glulxe 0.4.4, which implements the Glulx 3.1.1 specification. This adds support for Inform 6 veneer acceleration, which can greatly increase the performance of games compiled to take advantage of this.
Glulxe 0.4.3 (Windows Glk 1.36)
  • Fixed a bug with glk_stylehint_clear() ignoring any user set values.
Glulxe 0.4.3 (Windows Glk 1.35)
  • The implementation of the algorithm for scaling images has been sped up.
  • When the user tries to enter an input line wider than the window, the input is split over multiple lines.
  • Fixed a bug with sound volumes not being set correctly if the main window was not yet open.
  • Fixed a bug with the scrollback dialog not appearing when a translation DLL was in use.
  • Fixed another bug that occasionally led to a [More] prompt not appearing when it should.
  • The C compiler used to compile Glulxe has been changed to GCC, resulting in an increase in the speed of the interpreter.
Glulxe 0.4.3 (Windows Glk 1.34)
  • Improved the logic used to output Unicode text: now if a character can be drawn in any font on the system, that font will be used where needed. For best results a 'Unicode' font (e.g. "Arial Unicode MS" or "Code 2000") should be installed, though it doesn't need to be selected as either the proportional or fixed width font.
Glulxe 0.4.3 (Windows Glk 1.33)
  • Fixed a bug that occasionally led to a [More] prompt not appearing when it should.
  • Fixed a bug that caused an initial carriage return printed in a text buffer window to be ignored.
  • Rewrote the speech support to use SAPI 5, which comes with Windows XP and later.
  • Speech options are now set in a separate "Speech" tab on the options dialog.
  • Pressing the Break key (Ctrl+Pause) stops any currently playing speech.
Glulxe 0.4.3 (Windows Glk 1.32)
  • Updated to Glulxe 0.4.3, which fixes several bugs in 0.4.2.
Glulxe 0.4.2 (Windows Glk 1.32)
  • Added the menu item About This Game which, when playing an appropriately packaged Blorb file, shows a dialog with the cover art and description of the game. This dialog is also shown the first time a game is played.
  • Added an option to say whether, for a game with an iFiction record, the About This Game dialog is never shown, only shown the first time a game is loaded, or shown every time.
  • Updated to the latest version of ModPlug, which is now compiled into the library.
  • glk_fileref_create_by_name() now removes directory separator characters from its file name argument, replacing them with dashes.
Glulxe 0.4.2 (Windows Glk 1.31)
  • Minor improvements to the interpreter's appearance under Windows Vista.
  • Fixed a long-standing bug in glk_window_set_arrangement() when changing the direction of the window sizing constraint.
  • Fixed the incorrect clipping of italic text.
  • Pressing a key in any window will now clear any pending [More] prompts in any other windows, rather than requiring the user to select the affected window.
  • Changed the default values of a few options: window borders are now off by default, and the default indentation in text buffer windows is one unit, rather than zero.
Glulxe 0.4.1 (Windows Glk 1.30)
  • Updated to Glulxe 0.4.1, which implements the Glulx 3.1.0 specification.
Glulxe 0.4.0 (Windows Glk 1.30)
  • Updated to Glulxe 0.4.0, which implements the Glulx 3.0.0 specification.
  • Updated to Glk 0.7.0, which adds Unicode support.
Glulxe 0.3.5 (Windows Glk 1.27)
  • Added support for Ogg Vorbis music resources, based on code submitted by David Moreno.
  • The file extensions .blorb, .glb and .gblorb can be used for Blorb files. The latter two indicate that the Blorb file contains a Glulx game.
Glulxe 0.3.5 (Windows Glk 1.26)
  • The input caret is now correctly restored after a save or restore file dialog.
  • The mouse cursor now changes to the correct image over hyperlinks when a translation DLL is in use.
  • Pressing Ctrl+V with the focus on a text buffer window that is waiting for input now pastes the contents of the clipboard into the input line.
  • The WindowWidth and WindowHeight keys in a configuration file now refer to the size of a single, full-size Glk window, rather than the entire window of the interpreter.
  • The WindowMask key in a configuration file now only takes effect if the WindowFrame key is set to "no".
Glulxe 0.3.5 (Windows Glk 1.25)
  • Images are now scaled with a bilinear filter, resulting in greatly improved appearance of scaled images.
  • When the interpreter is started, it attempts to load a Blorb file with the same name as the executable, so that you can rename the interpreter Foo.exe, distribute it with your game Foo.blb, and have the user start the game simply by starting Foo.exe.
  • Added true colour icons drawn by Javier San José.
  • Added this help file.
  • If a configuration file is loaded that specifies a window size, whether or not the window was previously maximized is now ignored: the window always appears with the specified size.
  • Images in the left or right margins of text buffer windows are now displayed correctly after a flow break.
  • The AIFF decoder now correctly handles chunks that are an odd number of bytes long.
  • Text grid windows in which the game asks for input don't now steal the focus from text buffer windows in which the game is also asking for input.
Glulxe 0.3.5 (Windows Glk 1.24)
  • Fixed a serious resource leak under Windows 95/98/Me.
  • Pressing the Pause key causes any windows blocking on a [More] prompt to update, regardless of whether or not they are the active window.
Glulxe 0.3.5 (Windows Glk 1.23)
  • The speed at which the text to speech output is spoken can now be set from the options dialog.
  • The scrollback dialog now opens at the end of the text, not the start.
Glulxe 0.3.5 (Windows Glk 1.22)
  • Fixed the annoying cursor flickering visible when games request timer events faster than about 100ms.
  • Added support for SONG music resources. The SONG format is essentially the same as MOD, only with the music samples stored as separate AIFF sample resources.
  • Added an Italian translation, by Tommaso Caldarola.
  • Updated to use the new look GUI elements under Windows XP.
Glulxe 0.3.5 (Windows Glk 1.21)
  • Added a Spanish translation, by Javier San José.
  • The scrollback buffer is no longer emptied when a text buffer window is cleared.
  • Added support for configuration files, which allow various properties of the interpreter's window to be set.
  • Now using the latest version of MODPlug's mppsdk.dll.
  • Fixed a problem with the speech routines excluding accented characters.
Glulxe 0.3.5 (Windows Glk 1.20)
  • Completely rewrote the sound code to use DirectSound directly.
  • The text printed in text buffer windows can now be spoken using Microsoft's Speech Engine.
  • Fixed the graphics scaling to produce better results.
  • Fixed a bug which caused glk_fileref_does_file_exist() to not return a useful result when called by a game.
  • Calling glk_stream_open_file(filemode_ReadWrite) will now create the file if it does not already exist.
  • The current style for a window is now set to its previous value after line input, rather than reverting to style_Normal.


Credits and License

Windows Glulxe package by David Kinder.
Windows Glk is copyright 1998-2012 by David Kinder.
Glulxe is copyright 1999-2010 by Andrew Plotkin.

You may copy and distribute both the source code and the compiled binaries freely, by any means and under any conditions, as long as the code and documentation is not changed. You may also incorporate this code into your own program and distribute that, or modify this code and use and distribute the modified version, as long as you retain a notice in your program or documentation which mention the above authors' names and the Glk and Glulx web pages:

Glk: | http://www.eblong.com/zarf/glk/
Glulx: | http://www.eblong.com/zarf/glulx/

The user interface for Windows Glk has been translated into Spanish by Javier San José, and into Italian by Tommaso Caldarola.

Windows Glk contains bitmap scaling code written by Eran Yariv. The code that handles Ogg Vorbis music resources is based on code submitted by David Moreno.

Windows Glk uses the following libraries:

  • jpeglib by the Independent JPEG Group.
  • libpng by Guy Eric Schalnat, Andreas Dilger, Glenn Randers-Pehrson, and others.
  • zlib by Jean-loup Gailly and Mark Adler.
  • libogg and libvorbis by the Xiph.org Foundation. (Click here for the license.)
  • MODPlug by Olivier Lapicque.


Ogg Vorbis License

Copyright (c) 2002, Xiph.org Foundation

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

- Neither the name of the Xiph.org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.